added Feb 2001 SDK

[windows-sources.git] / sdk / Feburary 2001 Platform SDK / DXReadMe.Txt

Microsoft® DirectX® 8.0 SDK 

Contents:

- WHAT'S NEW
- DIRECTX 8.0 SDK RELEASE NOTES AND KNOWN ISSUES 
- COMPILER SUPPORT

__________________________________________________________________



WHAT'S NEW:


DirectX Audio (DirectSound & DirectMusic)
=========================================

DirectX 8.0 audio covers both DirectSound and DirectMusic API's.  In 
DirectX 8.0, these API's are more closely aligned and tied together.

There are many new features.  They include:

   Effects processing on DirectSound Buffers
   DLS2 synthesis
        Arbitrary loop points
        Release waveforms
        Optional Filter per voice
        6-stage envelope
        Ramped volume scaling
        Time-stamped playback
   "Audiopaths":  a powerful and easy way to use the DirectMusic DLS2 synthesizer 
   for sound effects programming.
        Submixing of audio prior to 3D processing (by DLS2 synthesizer)
        Automatic streaming and ACM compression (ADPCM, etc.)
   Composition enhancements
   Audio Scripting

We also think you will want to look at using the DLS2 synthesizer as your 
main sound effects engine.  The DLS2 synthesizer is accessed primarily through 
the DirectMusic API's.  Please do not let the word, "Music" mislead you; the 
DirectX 8.0 DirectMusic API's have been enhanced *specifically* for sound effects
playback.  The new DirectMusic API's that are designed to support sound effects
refer to audiopaths. Please investigate audiopaths; they provide a lot of
cool features for sound effects.  For example, if you have multiple sounds 
that need to come from the same 3d location, you can pre-mix them (using Audiopaths) 
and use only one 3d hardware buffer to play them.

Parameter Validation:
DirectSound in particular has some greater parameter validation in place
when the DirectSound8 interfaces are used.

-Waveformats are more tightly parsed
-You can no longer create a DirectSoundBuffer with both CTRL_3D and CTRL_PAN set
-You can no longer create a DirectSoundBuffer with CTRL_3D set and a wave format
with more than 1 channel.  I.e. Only mono buffers may be created with CTRL_3D.

Scripting is very exciting.  It puts much of the control over the audio 
implementation of the game into the hands of the sound designer.  Using 
scripts, audio designers can change implementations, make the music 'magically' 
interactive, and play different sound effects based on in-game variables.  
It also drastically shortens the edit-integrate-listen cycle.  This should
result in improved sound effects and music, with much less game-programmer 
time required.

There are sections in the documentation on a new FullDuplex interface and
"Capture effects."  These interfaces are not currently supported.

If you are using DirectPlayVoice, you should use those interfaces.  If your
application requires audio capture outside of DirectPlayVoice, 
you should use the existing DirectSoundCapture interfaces.


Direct3D
========

Migration of DirectDraw into Direct3D:

In DirectX 8.0, DirectDraw® is fully integrated into Microsoft Direct3D
to enable drastically simplified application initialization, improved data 
allocation and management performance, and reduced memory footprint. 
The new Direct3D infrastructure provides the services that are called 
at relatively low frequency.  These services comprise:

- Creation of Direct3D
- Creation of resources (textures, vertex buffers etc)
- Display mode selection
- Presentation of rendered images to the display

New Graphics Features for DirectX 8.0 are:

Parallel vertex input streams for more flexible mapping to dynamic 
application data structures. Programmable vertex processing language 
enables programmers to write hardware shaders for:

- Morphing/tweening animation
- Matrix palette skinning
- User-defined lighting models
- General environment mapping
- Procedural geometry
- Any other developer-defined algorithm

Programmable Pixel processing language enables programmers to write 
hardware shaders for:

- Per-pixel lighting/bump mapping
- Per-pixel environment mapping
- Any other developer-defined algorithm

MultiSample Rendering support enables:

- Full-scene antialiasing
- Multisample effects such as motion blur, depth-of-field, etc.

Point Sprites enable:

- High-performance rendering of particle systems

3-D Volume textures enable:

- Range-attenuation in per-pixel lighting
- Volume atmospheric effects
- Easy texturing of very complex geometry

Higher-Order Primitive Support:

- For enhancing the appearance of 3-D content
- Facilitating mapping of content from major 3-D authoring tools

Higher-Level Technologies:

- 3-D content creation tool plugins for export into Direct3D of skinned 
  meshes using a variety of Direct3D techniques such as, multi-resolution 
  LOD geometry, and higher order surface data.

Direct3D Feature Notes:

No significant API changes are contemplated beyond this point.  
All implemented features have been tested individually 
to some extent, but they have not been tested in exhaustive combinations 
yet.  Many features in DirectX 8.0 are awaiting new hardware, however 
there is at least one implementation available for each of the features 
shipped:

- Programmable vertex shaders are supported on the host CPU. On CPUs they 
  will operate with performance comparable to HW implementations and can be 
  used immediately for DirectX 8.0 prototyping and development. 
- Programmable pixel shaders are supported on the host CPU using refrast 
  only. These can be used for prototyping DirectX 8.0 shaders for use when 
  hardware ships. 
- Parallel DMA data input is supported on refrast and the SW geometry pipeline.
- Point Sprites are supported in refrast, software T&L pipeline, and should
  be supported in a prototype DirectX 8.0 driver from at least one hardware 
  manufacturer.
- Volume Textures are supported in refrast. 
- Multisample rendering is supported in refrast and future hardware. 
- Higher-Order Primitives are supported in refrast and via D3DX utilities.  

D3DX
====

Debug Binaries for D3DX:

The D3DX library is a static library. However, to help debugging, we also 
have a debug only dynamic library of D3DX in DirectX 8.0. To use this, link 
with the d3dx8d.lib which is an import lib corresponding to the D3DX8D.DLL. 
If you are reporting a bug and sending Microsoft an example that reproduces 
that behavior, please make sure the executable is linked to the dynamic debug 
library.

The dynamic debug d3dx8 library is for debugging only and is not intended 
for use of shipping applications. D3DX8D.DLL is installed as part of the 
DirectX 8.0 SDK setup, not as part of the redistributable runtime setup. 
This will not be available as part of future operating systems.

If apps want to statically link to the debug d3dx8 library they need to 
link to d3dx8dt.lib. To statically link to a retail d3dx8 library please 
link to d3dx8.lib.

The D3DX Effect Framework

The D3DX effect framework allows you to define shading effects using a text 
file that describes the various techniques of implementing an effect. For 
an example of an effect file see water.sha in the C samples media directory.


DirectInput
===========

DirectInput for DirectX 8.0 features a major addition, the DirectInput 
Mapper. The Mapper makes it possible for applications to code to their 
in-game actions, without the effort of figuring out the actions represented 
on the device itself. Additionally, the Mapper makes user configuration 
of devices much simpler by offering a default configuration UI. 

DIPROP_KEYNAME is supported by the IDirectInputDevice8::GetProperty 
method. DIPROP_KEYNAME retrieves the localized key name, in the form 
of a DIPROPSTRING, from a DirectInput DIK_* value.

DIPROP_SCANCODE is supported by the IDirectInputDevice8::GetProperty 
method. DIPROP_KEYNAME retrieves the device scancode, in the form of a 
DIPROPDWORD, from a DirectInput DIK_* value.  


DirectPlay
==========

DirectPlay has been completely rewritten in DirectX 8.0 to provide the 
robust scalability required to build high performance, massively 
scaleable network games. With version 8.0, DirectPlay also provides 
voice communication via the DirectPlay Voice API.

Note: In these release notes the phrases "DirectPlay4", "DirectPlay4 
interface" or "DirectPlay4 session" are used to mean the IDirectPlay4 
interface or a session hosted using the IDirectPlay4 interface, even 
if that interface or session is implemented using the dlls that are 
part of DirectX 8.0. "DirectPlay8", "DirectPlay8 interface", and 
"DirectPlay8 session" mean the IDirectPlay8... family of interfaces,
or a session hosted using the IDirectPlay8... family of interfaces.

Since DirectPlay8 has been completely re-written from the ground up, 
the DirectPlay8 interfaces are not extensions of the existing 
DirectPlay4 interfaces. i.e. the DirectPlay8 interfaces do not 
inherit from the DirectPlay4 interfaces in the object oriented sense.

Also, DirectPlay8 sessions are not network compatible with DirectPlay4
sessions.

Note that the DirectPlay4 interfaces are still present in DirectPlay8
and are still compatible with previous versions of DirectPlay. So games
written for DirectPlay4 will still run on systems with DirectX 8.0 
installed.

To enable maximum scalability, DirectPlay8 uses a callback model. All
indications from DirectPlay8 are delivered to the application via an
application supplied callback function. Therefore DirectPlay can indicate 
multiple events to the application in parallel on different threads.

Additionally, performance critical operations such as Send and Receive 
can be performed without copying data, and without thread switching. 

This programming model allows DirectPlay applications to achieve maximum 
possible performance and scalability on both single-processor and 
multi-processor hardware.  

DirectPlay8 also adds:
  - Better support for NATs, Firewalls, and Proxy Servers
  - Application defined payloads on session enumerations and replies
  - Revised addressing scheme that is URL ruled based designed to be human 
    readable and portable
  - The use of I/O completion ports in Windows 2000
  - Improved ease of use through the removal of obtuse services, for example 
    groups within groups

The DirectPlay Voice interfaces allow you to quickly and easily establish 
voice communications over an existing DirectPlay8 or DirectPlay4 session. 

DirectPlay Voice provides the following features:
  - Peer to peer, forwarding server, and mixing server voice topologies
  - A variety of codecs from 1.2kbit/sec to 64kbit/sec, that can be used 
    royalty free in DirectPlay Voice.
  - Voice detection to automatically trigger voice transmission
  - Automatic gain control to automatically adjust the recording volume level
  - Adaptive queuing that provides a smooth speech stream with minimum latency
    over different and changing network conditions
  - Integration with DirectSound & DirectSoundCapture
  - Sound Hardware Test wizard
  - Support for IDirectPlay8 and IDirectPlay4 transport sessions

DirectPlay8 still has all the benefits of previous versions of DirectPlay, 
including:
  - session setup and teardown
  - session discovery
  - application launching
  - player management
  - group management
  - client/server and peer to peer operation
  - peer to peer host migration
  - bandwidth throttling protocol


DirectShow
==========

DirectX 8.0 marks the first release that DirectShow has been part of the
core DirectX redistribution. This means that for the first time,
applications using DirectShow need not install a separate redist, and 
current DirectX users can now take advantage of DirectShow in their
applications. Adding to the existing capabilities for audio and video
playback and capture that DirectShow provided, this new release also
provides the following new features:

Windows Media Format Support:  Two new filters enable DirectShow applications
to read and write files in Windows Media Format. The ASF Reader filter 
reads and parses Windows Media Format files. The ASF File Writer filter 
writes Windows Media Format files; it also does the necessary multiplexing 
and compressing. 

DirectShow Editing Services (DES):  This is a complete API for timeline and
switching services built on top of DirectShow. This API implements the
core of non-linear editing services, and allows for the creation of
composite media from a variable number of source audio and video streams. 
By allowing real-time effects and transitions, true "on-the-fly" source 
switching, run-time compositing, run-time seeking, and graph management,
DES provides a powerful high-level way to use DirectShow, while
still allowing applications to access lower-level DirectShow functions.
DES replaces cutlists, which are no longer supported.

New DVD Support:  Two new interfaces, IDVDControl2 and IDVDInfo2, greatly expand
the functionality of the DVD Navigator. The new MSWebDVD ActiveX® control 
makes this functionality available to script-based applications. 
New DVD features include: Karaoke multichannel audio support, audio volume 
control through IBasicAudio, support for frame stepping and frame-accurate 
seeking, simplified access to DVD text information strings, and improved support 
for parental management controls. 

DirectX Media Objects:  DirectX Media Objects (DMOs) are a new way to write 
data-streaming components. Like DirectShow filters, DMOs take input data and use 
it to produce output data. However, the application programming interfaces 
(APIs) for DMOs are much simpler than the corresponding APIs for DirectShow. As 
a result, DMOs are easier to create, test, and use than DirectShow filters.
A wrapper filter is provided to allow DMOs to be used within DirectShow. 

Media Parameters:   Media parameters are a new set of APIs that support run-time 
changes to an object's properties. They offer precise control over properties 
that change rapidly and require both high performance and repeatability. They 
enable a property to follow an exact curve, such as a sine wave or 
inverse-square curve, in real time.

New Filters:
- MJPEG Decompressor: Decodes a video stream from motion JPEG to uncompressed video 
- MJPEG Compressor: Compresses an uncompressed video stream using 
     motion JPEG compression. 
- Null Renderer: Discards samples without displaying or rendering the sample data.
     Applications can use this filter to discard data from a stream. 
- Sample Grabber: Retrieves media samples as they move through the filter graph.
     Applications can use this filter to obtain poster frames or other media data. 

Dynamic Graph Building:  DirectShow applications can now change the graph 
while it is still playing. This allows new audio or video streams to be added 
to a graph, effects to be inserted in the graph without any visible gap in the
playback, and chains of filters to be paused and run independent of the main graph.

Push Model Clock Support:  This allows for improved synchronization between
audio and video streams. The default audio renderer can now be slaved to
another clock, allowing for applications to deal with timing differences
between clocks on sound cards and capture devices, among other scenarios.

Graph Edit enhancements:  GraphEdit now displays filter registration information
in the Insert Filters dialog and allows you to spy on existing graphs in
external processes (if those processes register their graphs).


DirectMusic Producer
====================

This version of Producer features many new features to aid in both 
authoring and auditioning of DirectMusic content.  These features include 
authoring support for audio path configurations, which manages pchannel 
and synth assignments as well as effects routing, the new DLS level 2 
format (which includes stereo waves, layering of regions, and filtering) 
and a new API for scripting, which allows composers and sound designers 
to integrate audio content directly into an application.  Other major 
features include new track types, including a wave track, a script 
track, a secondary segment trigger track and a melody track, which 
integrates a variable approach with greater control of form. 


DirectX Control Panel
=====================
Developers can now toggle between DirectX retail and debug system components 
through the DirectX Control Panel. 


Broadcast Driver Architecture
======================

Broadcast Driver Architecture (BDA) is a set of Ring 0 and Ring 3 software 
components based on the DirectShow® architecture for streaming multimedia 
broadcast content. BDA is also a specification that defines how custom 
components, such as filters for parsing private data, interface with the 
rest of the system. Digital-TV applications can use the Ring 3 components 
to build filter graphs, implement a single model for tuning across all 
network types, automate the storage and retrieval of electronic program 
guide information, and capture IP data including ATVEF announcements, 
triggers, and packages.

__________________________________________________________________



DIRECTX 8.0 SDK NOTES AND KNOWN ISSUES
  

DirectX Audio (DirectSound & DirectMusic)
=========================================

Below are some known issues with DirectMusic and DirectSound in 
DirectX 8.0 that you may encounter.  

- ParamEQ and Distortion effects have parameters that are sampling rate 
  dependent.
  Setting these params to a value that is out of range for that sampling 
  rate will result in:
     Distortion:  Parameters are 'clipped' at the valid range for the 
                  sampling rate
     ParamEQ:  If the frequency is greater than can be supported by the 
               sampling rate, the effect is disabled-  In the DirectMusic 
               3DAudio sample, there may be some breakup if Doppler is set > 4
- DirectSound buffers that are created with DSBCAPS_CTRLFX must be at 
  least 100ms in length.


Direct3D
========

- All executables compiled against earlier DirectX 8.0 betas must be 
  recompiled with this version to run.
- Alt-enter in the samples results in texture corruption for some drivers. 
  Workaround: Get newer drivers.
- The value for MaxPrimitiveCount defines the max number of vertices
  as well as the max number of primitives that can be sent to a 
  DrawIndexedPrimitive or DrawPrimitive call.
- A bug in the Windows2000 kernel causes an issue upon mode-switches for 
  AGP surfaces locked with the NOSYSLOCK flag. The contents of any such 
  surface may  become inaccessible for the duration of the NOSYSLOCK lock 
  if a mode-switch happens after the Lock and before the Unlock. This happens 
  for both DX7 and DX8 applications. The most likely scenario is a DX8 
  application running on a driver that supports hardware vertex buffers, 
  but using software vertex processing (fixed or shader). Under these 
  scenarios, Direct3D might keep a NOSYSLOCK lock on an AGP vertex buffer. 
  If the user alt-tabs out of the application or does anything else to cause 
  a mode-change, the thread writing into the vertex buffer may fault. There 
  is no known workaround. Microsoft will fix this issue in the next version 
  of Windows and will attempt to ship a fix in a future Windows2000 
  Service Pack.
- A bug in the DX6 and DX7 implementation of 
  IDirectDraw*::GetDeviceIdentifier causes the DirectDraw runtime to write 
  four extra bytes past the end of the structure. To work around this issue, 
  allocate an extra four bytes at the end of your DDDEVICEIDENTIFIER* 
  structure. This bug does not exist in the IDirect3D8::GetAdapterIdentifier 
  version.
- The Direct3D8 run-time exhibits the following behvior on all Windows NT 
  platforms. Run a full-screen Direct3D8 application, press Ctrl-Alt-Del, 
  press ESC. The desktop will appear, but the display card will still be in 
  the application's resolution, not the proper desktop resolution. (The user 
  may alt-tab back to the application at this time.) A fix for this will be 
  in the next release of DirectX, and the problem will be fixed in the next 
  version of Windows NT. Developers are urged NOT to try to work-around this 
  problem nor code their own solutions, since such solutions are very likely 
  to interact poorly with our own fix.
- Terminating a process with un-released vertex buffers on Win9x DX7 APIs 
  can cause instability. This is caused by a bug in the automatic per-process 
  cleanup code in DirectDraw which causes VBs to be leaked permanently (until 
  reboot) on all Win9x platforms: Windows 95, 98, Millenirum. Applications 
  should be carefully coded to ensure all Vertex Buffers are correctly released
  before exiting the process.
- Applications should be careful when responding to the WM_MOUSEMOVE message. 
  If the application calls IDirect3DDevice8::SetCursorPosition with a coordinate 
  that is outside the current display mode size, then the Direct3D run-time may 
  cause another WM_MOUSEMOVE, which may cause the application to call 
  IDirect3DDevice8::SetCursorPosition again, resulting in an infinite loop. 
  The application should either be careful not to call 
  IDirect3DDevice8::SetCursorPosition  with invalid positions, or should never 
  call IDirect3DDevice8::SetCursorPosition  with repeated positions.
  One common scenario for generating invalid mouse cursors is to remove the 
  menu style from a window incorrectly when going full-screen. The SDK sample 
  applications incorrectly use SetWindowLong to remove the menu bar from the 
  window before going fullscreen. The correct technique is to call 
  "hOldMenu = SetMenu(hWnd, NULL)'" before going fullscreen, and then 
  "SetMenu(hWnd, hOldMenu);" before returning to windowed mode.
- When using the function ValidateDevice on Win9x the return value will be 
  DD_OK if it is successful.

Point Sprites:  

- When using the Direct3D software T&L pipeline (device created with 
  D3DCREATE_SOFTWARE_VERTEXPROCESSING flag set or with 
  D3DCREATE_MIXED_VERTEXPROCESSING flag and software vertex processing 
  toggled on), then point sprite support is guaranteed.  When using 
  hardware vertex processing, some older drivers may not support point 
  sprites, indicated by d3dcaps->MaxPointSize = 0.  Upgrading to a DX8 
  driver for these parts will enable them.

    To ensure consistent behavior for point sprite support, set
        D3DRS_CULLMODE = D3DCULL_NONE 
        D3DRS_FILLMODE = D3DFILL_SOLID
    when rendering point sprites.

Vertex Shaders:  

- Two vertex shader instructions may produce implementation-specific 
  results for out-of-range inputs, such as the log of a negative number.
  The log, logp and y- component of the lit instruction macro should not
  be passed negative values for this reason.

Driver/Device Specific Issues:

- The Windows Millennium driver for the ATI Rage 128 fails (draws nothing) 
  when using vertex shaders which output more than two texture coordinates 
  per texture coordinate set when the D3DTTFF_PROJECTED bit is not set.

D3DX
====

- This product includes software developed by the University of California,
  Berkeley and its contributors D3DX Mesh APIs.
- The ID3DXSkinMesh interfaces currently only support 16-bit mesh. 32-bit 
  mesh support is not yet implemented.
- All other D3DX Mesh interfaces do support 32-bit meshes even though the 
  docs say they do not.
- D3XGenerateAdjacency currently ignored the epsilon value and uses 0.0f 
  as the epsilon.
- In D3DXMatrixPerspectiveFOV, the aspect ratio is x/y instead of y/x.


DirectInput
===========

 - There is a bug in DirectInput which causes the Logitech Wingman Formula wheel to 
   report pedal data on the wrong axes.  
 - There are some know issues that can cause mouse behavior to be very sluggish 
   when debugging using DirectInput.   There are two reg files that will
   assist with this issue.  They are:
      Mouse and Keyboard Emulation On.reg
      Mouse and Keyboard Emulation Off.reg
   "Mouse and Keyboard Emulation On.reg" will force all mouse calls through 
   dinput emulation, thus making the mouse perform properly inside the debugger.  
   "Mouse and Keyboard Emulation Off.reg" will turn off force emulation.
   Only use these keys on development machines, they are not intended to be 
   redisted as they are a global setting that effects all Direct Input clients.
 - The following devices are supported with device images in this release.    
      + ACT LABS RS
      + ACT LABS Force RS
      + Gravis Xterminator Dual Control 
      + Gravis Blackhawk Digital        
      + Gravis Gamepad Pro USB
      + Gravis Gamepad Pro
      + Gravis Eliminator Gamepad Pro
      + Gravis Xterminator Digital GamePad
      + InterAct/3dfx SV-262A HammerHead Fx
      + InterAct Axispad
      + InterAct SV-251 Raider Digital
      + Logitech WingMan Formula (Yellow)
      + Logitech WingMan Extreme Digital 3D
      + Logitech WingMan Gamepad Black (USB)
      + Logitech Wingman Rally Force USB
      + Logitech Wingman Rumblepad
      + Microsoft Sidewinder Gamepad Pro
      + Microsoft SideWinder Force Feedback Wheel
      + Microsoft SideWinder Force Feedback Pro
      + Microsoft Sidewinder FF 2
      + Microsoft Sidewinder Dual Strike
      + Microsoft Sidewinder Precision 2
      + Microsoft Sidewinder Plug and Play
      + Microsoft SideWinder Game Pad
      + Microsoft SideWinder Precision Racing Wheel
      + Microsoft SideWinder Precision Pro
      + Microsoft SideWinder Freestyle Pro
      + Microsoft SideWinder 3D Pro


DirectPlay
==========

The following are known issues with DirectPlay in this release that 
you may need to work around.

- Note that the dwTimeoutUntilKeepAlive member of the DPN_CAPS structure 
  specifies a minimum value. The first keepalive packet may be sent as 
  much as 30 seconds later than the minimum value specified in this 
  member. For example, if you set dwTimeoutUntilKeepAlive to 60000 
  (60 seconds) the first keepalive packet may be sent anywhere from 
  60 to 90 seconds after the last normal packet was sent.
- To use DirectPlay Voice in full duplex mode, we recommend that you update
  to the latest drivers for your audio device. Some older drivers do not
  provide reliable full duplex performance.
- If you connect to a location that you have enumerated, the enumeration 
  will be canceled automatically for you.  If you attempt to do a cancel 
  asynchronous operation on this enum after the connect is completed you 
  will get back DPNERR_USERCANCEL error code.  Be aware that this is the
  expected behavior and that you should not exit with an error condition.
- The modem service provider implementation for DirectPlay8 requires 
  TAPI 2.0 functionality.  TAPI 2.0 is available as an installed component 
  on Windows 98 and later, but not on Windows 95.  If your application 
  requires modem functionality on the Windows 95 platform, the TAPI 2.0 
  patch for Windows 95 can be obtained on the Microsoft FTP site 
  (ftp://ftp.microsoft.com/developr/TAPI/tapi2195.zip) and distributed 
  with you application.

Notes on NATs (Network Address Translators):

- There are many different NAT solutions available, some of which are
  different from others. We have attempted to document some of the issues
  with various NAT solutions, but is not comprehensive.  Please refer to 
  the DirectX Developer Page at http://msdn.microsoft.com/directx for 
  further information on these issues.

DirectPlay Voice codecs via Windows ACM (Audio Compression Manager):

- DirectPlay Voice uses the following codecs via the Windows ACM:
   - Microsoft ADPCM
   - Microsoft GSM
   - DSP Group Truespeech
- Installation of these codecs with Windows is optional. If they 
  are not installed, then one or more of the compression types in 
  DirectPlay Voice will not function. If the application attempts 
  to use a compression type that is not functional due to a missing 
  ACM codec, it will receive the DVERR_COMPRESSIONNOTSUPPORTED 
  return code.
- On Windows 2000, the user can install these codecs through the 
  Add/Remove Hardware wizard. The user should select 
  "Add/Troubleshoot a device". When a list of hardware is presented, 
  the user should select "Add a new device", then on the next 
  page select "No, I want to select the hardware from a list". 
  This will bring up a list of hardware. Select "Sound, video, and 
  game controllers". The "Audio Codecs" item is listed under 
  "(Standard system devices)". 
- On Windows 9x, the user can install these codecs through the 
  Add New Hardware wizard. When prompted, the user should select 
  "No, I want to select the hardware from a list". In the list of 
  device types, codecs are listed under "Sound video and game 
  controllers". The codecs are listed under two manufacturers. 
  The ADPCM and GSM codecs are listed under "Microsoft Audio 
  Codecs" and the Truespeech codec is listed under "DSP Group".


DirectShow
==========

- The GraphEdit Tool (and some of the DirectShow samples) requires MFC42.DLL
  to be present on the system.  The DirectX SDK Setup does not install this 
  DLL.  This will only be an issue on Windows 95 systems and will require you
  to install Microsoft Visual C++ to acquire the DLL.
- Application development using the DirectShow base classes libraries requires
  installation of the DirectShow samples.  The source code for the base classes
  is now included as a sample project, rather than as a separate Classes\Base 
  directory.  You must compile these base classes to generate strmbase.lib and 
  strmbasd.lib, which are no longer installed as binary files.   If you are
  linking with strmbase.lib or strmbasd.lib with your own application, be sure
  to build and link with the updated DirectX 8 libraries (instead of the older
  libraries that are installed with Visual C++ or the Microsoft Platform SDK).
- The samples included with the SDK are configured to compile and link with 
  the updated libraries, which are generated by building the BaseClasses project.  
  Further build instructions are provided in:
          <DXSDKInstallFolder>\samples\Multimedia\DirectShow\readme.txt.
- The <streams.h> header file, along with many other DirectShow-specific header
  files, is now located in the DirectShow samples BaseClasses directory, 
  which includes the BaseClasses source code and header files.  You must add 
  the BaseClasses directory to the beginning of your project's include path 
  settings in order for Visual C++ to find all of the updated header files.
- To use the Teletext Decoder Fonts that are shipped with DX8, make sure that
  the WST_* fonts are installed by examining the \windows\fonts directory.
- There is a known problem with the MP3 decoder filter when used with
  Audio Effects DMOs.  If you add an audio effect DMO (like WavesReverb, Echo,
  or Flange) to an existing MP3 filter graph, the audio could be played back
  at double speed.  The problem would occur whenever the MP3 decoder is connected 
  to a downstream audio effect dmo (via the dmo filter wrapper) that offers a 
  default audio input type which doesn't match the native format of the 
  uncompressed MP3 stream.  For example, if you render a 22kHz MP3 file and 
  add a DMO Audio effect, the MP3 filter could misinterpret the input type as
  being 44kHz when it is actually 22kHz.  This would not be a problem for 44kHz 
  MP3 files.  This issue will be fixed in a future release.
- If you have the SDK on CD-ROM, the Extras\DirectShow\Media  directory 
  contains additional media that can be used with DirectShow and the DirectShow
  Editing Services (DES) interfaces.  We have included DV-encoded AVI videos, 
  larger MPEG videos, and higher-quality JPEG images.  Since the DV files are 
  very large, you should copy them to your hard disk before playing them to 
  ensure the best performance.
- Remote graph spying with GraphEdit works only on Windows 2000.
- The DirectShow Editing Services (DES) Color Generator source filter may 
  generate blue or green components incorrectly if they have small values.  
  For best results, use solid primary colors or set Blue and Green 
  components to values of either 0xFF or 0x00.


Broadcast Driver Architecture
======================

Known issues with Broadcast IP Data Reception under Windows 2000:

- After rebooting a Windows 2000 system with a BDA receiver card installed,
  the BDA NDIS IP NIC is not immediately active.  It becomes active only 
  when an application inserts the BDA IPSink filter into a graph and connects
  its input pin.  Once activated by connecting the IPSink filter's input pin,
  it takes 20 to 30 seconds for the BDA NDIS IP NIC to be assigned an IP 
  address.  The address assigned will be a Net 10 address.  Once activated, 
  the BDA NDIS IP NIC will remain active until the system is rebooted.
- There may be some applications that use the BDA NDIS IP NIC as the default 
  LAN adapter.  These apps will fail if the BDA NDIS IP NIC is active.  To 
  de-activate the BDA NDIS IP NIC, reboot the system and do not run a TV graph 
  or application.


Documentation
=============

This section contains corrections to the following components of the DirectX SDK documentation:

  DirectX Graphics (Visual Basic)
  DirectPlay
  DirectShow

===============================
DirectX Graphics (Visual Basic)
===============================

---------------------------
D3DDevice8.SetRenderTarget
---------------------------

The D3DDevice8.SetRenderTarget method takes a third argument that is reserved for future use. It must be set 0. 


==================
DirectPlay (C/C++)
==================


--------------------------------
IDirectPlay8Peer::GetPeerAddress
--------------------------------
You cannot call GetPeerAddress() on yourself.


----------------------------------
IDirectPlay8LobbyClient::Initialize
----------------------------------
Initialize should include error codes NOTALLOWED and ALREADYINITIALIZED.  

 
DPNERR_NOTALLOWED is returned when a user attempptsd to initialize more than one instance of the DirectPlay8LobbyClient per process.

DPNERR_ALREADYINITIALIZED is returned when a user tries to call this method more than once.

----------------------------------
IDirectPlay8LobbiedApplication::Initialize
----------------------------------
This method should include error codes NOTALLOWED and ALREADYINITIALIZED.  
DPNERR_NOTALLOWED is returned when a user attempptsd to initialize more than one instance of the DirectPlay8LobbiedApplication per process.

DPNERR_ALREADYINITIALIZED is returned when a user tries to call this method more than once.


------------------------------------------
IDirectPlay8LobbyClient::EnumLocalPrograms
------------------------------------------

This method returns DPNERR_DOESNOTEXIST when the GUID that is specified for the application is not registered. 


-----------------------------
IDirectPlay8Server::SetSPCaps
-----------------------------

This method should have a third parameter: dwFlags. It is reserved for future use and should be set to zero.


-----------------------------
IDirectPlay8Peer::SetSPCaps
-----------------------------
This method should have a third parameter: dwFlags. It is reserved for future use and should be set to zero.

-----------------------------
IDirectPlay8Client::SetSPCaps
-----------------------------
This method should have a third parameter: dwFlags. It is reserved for future use and should be set to zero.

=========================
DirectPlay (Visual Basic)
=========================


--------------------------------
DirectPlay8Peer.GetPeerAddress
--------------------------------
You cannot call GetPeerAddress() on yourself.

-----------------------------------
DirectPlay8Peer.GetLocalHostAddress
-----------------------------------
This method is missing from the documentation. The syntax is:

    GetLocalHostAddress([lFlags As Long]) As DirectPlay8Address

The lFlags parameter is reserved and should be set to zero.

The method returns a DirectPlay8Address object that contains the local host address.


==========
DirectShow
==========


-------
General
-------

Although DirectShow does provide some APIs for Visual Basic and script developers, these are not extensive enough to warrant a separate Visual Basic compiled help file for DirectShow. Therefore all the DirectShow APIs, both for Visual Basic and C++, can be found under the DirectX C++ node. Note: The DirectShow documentation for Whistler Beta 2 is at an incorrect level in the Table of Contents.  Look for it in the next release in its correct position one level under the DirectX C++ node.

----------------------
Broadcast Architecture
----------------------
The old Broadcast Architecture documentation is now included in the DirectShow documentation under the title "Microsoft TV Technologies." 

-----------
Guide Store
-----------
Under Microsoft TV Technologies, the Guide Store APIs were revised significantly after the documentation was "locked down" for beta 2. The new APIs  will be documented in the next release. 

--------------------------------------
Video Mixing Renderer late corrections
--------------------------------------

IVMRSurfaceAllocate::AllocateSurface() can also return E_FAIL if passed an invalid lpAllocInfo->lpHdr. 

Before calling AllocateSurface explicitly from the client application, one should call IVMRSurfaceAllocator::FreeSurface()  to be sure that CAMDDrawMonitorInfo::pDDSDecode ( DDraw Decoding Surface Front Buffer) is NULL.  Otherwise, the debug version of quartz.dll gives an assertion. 


 

Samples 
=======

Miscellaneous Issues:
 
- Some samples will compile with errors with the UNICODE flag defined.

Direct3D Samples:

- There are miscellaneous issues with some display hardware & drivers.
  Please let us know of any problems you encounter and specify whether you
  believe it is sample or driver related.

DirectShow Samples:

- There are several .XTL sample files in the \media folder.  These files 
  demonstrate some of the functionality available in the DirectShow Editing 
  Services.  You can render these files using the XTLTest C++ sample and 
  the XTLTestVB and DexterVB VisualBasic samples.  All provided XTL files 
  refer to media that ships in the SDK's media directory.  Rendering XTL 
  files is a great way to get an idea of what the new DirectShow Editing 
  Services APIs make possible.  For a simple demo, drag a few of the SDK 
  media directory's sample .XTL files onto the XTLTestVB sample's client area.
- The DirectShow Visual Basic samples demonstrate more of the DES functionality 
  than the C++ samples.  Be sure to run SlideShowVB and TrimmerVB if you are 
  interested in DES.  You can also use the DexterVB ("Dexter Explorer") 
  application as an XTL development/test tool.
- The Texture3D sample is known to fail on some systems (referencing
  invalid memory), for which you may see an error message.  This failure is
  in initialization of D3D.  We recommend updating your video card drivers
  to the most current revision, as that usually resolves the problem.
- The DirectShow IDL files are currently located in the
  \include directory of the SDK for your convenience. 
- You will be required to build the \BaseClasses libraries before any sample
  that depends on them can be built or executed.  Please review the Readme.Txt 
  file in the DirectShow samples root directory for more information on 
  building the samples.


DirectX for Visual Basic Samples:

- DBMON.exe is a console application which allows the Visual Basic DirectX 
  developer to take advantage of extended output that debug installs of 
  DirectX provide. This application works only under Windows 2000. 
  To use, execute the application. All debug output will be captured and sent 
  to the console window. If you are not seeing debug output, ensure that 
  you have installed the debug version of DirectX, and that you are running 
  Windows 2000.
- DXVB Messenger Server is the server portion of a client/server instant 
  messaging application.  This sample requires the use of ActiveX Data Object
  (ADO) to maintain the data needed.  If you are running Windows 9x, you must 
  have the latest version of ADO installed on your machine to compile or run 
  this sample.  You can install the latest ADO while Visual Basic Professional 
  is being installed or you can download the latest ADO from the web at:
  http://www.microsoft.com/data/ado/.  ADO is installed by default with 
  Visual Basic 6 Enterprise.
- If you are experiencing problems searching for and connecting to sessions 
  using DirectPlay for VisualBasic, you may need to update your system.  
  To update, install DCOM98 from:
      http://download.microsoft.com/msdownload/dcom/98/x86/en/dcom98.exe 


Other
=====

- The DirectDraw "Debug Level" slider in DirectX Control Panel Applet does 
  not function.   Instead use the "Debug Output Level" slider on the Direct3D 
  tab, this will effect both DDraw and D3D8.   Also note that DirectDraw labels
  it's debug spew as coming from "Direct3D8".
- The DirectX runtime will not operate on NEC PC98 systems.  SDK and Runtime 
  installations have been intentionally blocked on this system.
- The DirectX 8.0 runtime requires a Pentium compatible CPU for operation.  
  The DirectX runtime setup will not install on processors that do not report 
  Pentium compatibility.  Some older Cyrix processors, while compatible with 
  the Pentium instruction set, report as x486 processors, and thus do not 
  support installation of the DirectX 8.0 run time.
- Windows 95 Japanese Systems will require MS UI Gothic patch for Windows 95 
  or Internet Explorer 5.0 (or after) for the DirectX Control Panel to display 
  properly. MS UI Gothic Patch can be found at 
  http://www.microsoft.com/JAPAN/win95/msgotupd/default.htm and IE5 (or after)
  can be found at http://www.microsoft.com/windows/ie/default.htm.

__________________________________________________________________


COMPILER SUPPORT

All DirectX 8.0 SDK samples are developed and compiled with Visual Studio 6.0.  
We have provided Visual Studio 6.0 DSP files for your convenience.  

All DirectX 8.0 libraries, with the exception of the DirectShow libraries, should
be compatible with Visual Studio 5.0 SP3 or higher.  

__________________________________________________________________


SPECIAL THANKS

Marlin Studios

Textures used in the Billboard sample, tree02S.tga, tree01S.tga & tree35S.tga,
are provided courtesy of Marlin Studios (http://www.marlinstudios.com).  
They are provided for use with this sample only and cannot be distributed 
with any application without prior written consent.  

Viewpoint Digital, Inc.

The model used by the Visual Basic AutoParts sample, engine1.x, is provided 
courtesy of Viewpoint Digital, Inc. (http://www.viewpoint.com).  It is provided 
for use with this sample only and cannot be distributed with any application 
without prior written consent.  V6 Engine Model copyright 1999 Viewpoint 
Digital, Inc..

3DCAFE and Platinum Pictures

The model in the Dolphin samples, Dolphin.x, is derived from the model files 
(dolphins.zip) provided courtesy of 3DCAFE and Platinum Pictures  
(http://www.3dcafe.com/).  It is provided for use with this sample only.  
For further terms of use please visit the 3DCAFE site or contact 3DCAFE.